gh-148829: Implement PEP 661 by JelleZijlstra · Pull Request #148831 · python/cpython

JelleZijlstra · 2026-04-21T13:59:21Z

Replaces JelleZijlstra#4. See python/steering-council#258.

Issue: Implement PEP 661 Sentinel Values #148829

📚 Documentation preview 📚: https://cpython-previews--148831.org.readthedocs.build/

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

bedevere-bot · 2026-04-24T13:59:52Z

🤖 New build scheduled with the buildbot fleet by @JelleZijlstra for commit 53a84b6 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F148831%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

ZeroIntensity

The C code and the corresponding documentation look good to me. I didn't look very closely at the tests.

sunmy2019 · 2026-04-24T14:49:07Z

+    assert(PyFunction_Check(func));
+    PyObject *r = PyFunction_GetModule((PyObject *)func);
+    if (!r) {
+        Py_RETURN_NONE;


Do we need a PyErr_Clear() here? (since if error occurs, usually we will return NULL)

@ZeroIntensity asked me to remove it (#148831 (comment)) because there is no scenario where this function can return NULL without an exception set.

Yeah, PyFunction_GetModule can only ever raise if the input argument is not a function, which we know will never be true here. We could add an assert(!PyErr_Occurred()) if you'd like.

+1 for assert(!PyErr_Occurred())

sunmy2019

LGTM

sunmy2019

Clarify the pickle document. So that people will see X = sentinel("Y") is not picklable.

sunmy2019 · 2026-04-24T16:26:34Z

+   *module_name* should be the name of an importable module if the sentinel
+   should support pickling.


Suggested change

*module_name* should be the name of an importable module if the sentinel

should support pickling.

For pickling to work, *module_name* must be the name of an importable

module, and the sentinel must be accessible from that module under a

path matching *name*. Pickle treats *name* as a global variable name

in *module_name* (see :meth:`object.__reduce__`).

Adding this would help people use pickle properly. People need to assign this sentinel instance to that module before pickle.dump.

sunmy2019 · 2026-04-24T16:27:22Z

+   Sentinels importable from their defining module by name preserve their
+   identity when pickled and unpickled.  Sentinels that are not importable by
+   module and name are not picklable.


Suggested change

Sentinels importable from their defining module by name preserve their

identity when pickled and unpickled. Sentinels that are not importable by

module and name are not picklable.

Sentinels are pickled using the standard mechanism for named global

objects. :meth:`sentinel.__reduce__` returns :attr:`~sentinel.__name__`,

which pickle interprets as the name of a global variable in

:attr:`~sentinel.__module__`. Sentinels that are not accessible from their

module under that name are not picklable.

Thanks, I agree we should expand more but feel it might be a bit much to say exactly how __reduce__ is implemented. I'll get back to this tonight and push some changes.

JelleZijlstra · 2026-04-24T16:48:50Z

Buildbot run: A few failures look unrelated

In file included from ./Include/internal/pycore_backoff.h:12,
                 from ./Include/internal/pycore_code.h:11,
                 from ./Include/internal/pycore_call.h:11,
                 from ./Modules/_ctypes/_ctypes.c:109:
./Modules/_ctypes/_ctypes.c: In function ‘set_stginfo_ffi_type_pointer’:
./Modules/_ctypes/_ctypes.c:2234:40: error: ‘FFI_TYPE_COMPLEX’ undeclared (first use in this function); did you mean ‘FFI_TYPE_DOUBLE’?
         assert(fmt->pffi_type->type == FFI_TYPE_COMPLEX);
                                        ^~~~~~~~~~~~~~~~
./Modules/_ctypes/_ctypes.c:2234:40: note: each undeclared identifier is reported only once for each function it appears in

But I also see

Traceback (most recent call last):
  File "/home/ubuntu/buildarea/pull_request.stan-aarch64-ubuntu.oddballs/build/Lib/test/pickletester.py", line 3254, in test_builtin_types
    s = self.dumps(t, proto)
  File "/home/ubuntu/buildarea/pull_request.stan-aarch64-ubuntu.oddballs/build/Lib/test/test_xpickle.py", line 190, in dumps
    return self.send_to_worker(python, data)
           ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
  File "/home/ubuntu/buildarea/pull_request.stan-aarch64-ubuntu.oddballs/build/Lib/test/test_xpickle.py", line 172, in send_to_worker
    raise exception
AttributeError: Can't get attribute 'sentinel' on <module 'builtins' (built-in)>

https://buildbot.python.org/#/builders/1865/builds/54

Which is a bit mysterious, is this looking at the builtins of another build?

sunmy2019 · 2026-04-24T16:54:21Z

Which is a bit mysterious, is this looking at the builtins of another build?

Yes. We need to patch this test. It tests pickle compatiblity acrosses python versions.

./python -m test test_xpickle -m test_builtin_types -u xpickle

sunmy2019 · 2026-04-24T16:55:46Z

diff --git a/Lib/test/pickletester.py b/Lib/test/pickletester.py
index 6366f12257..c2018c9785 100644
--- a/Lib/test/pickletester.py
+++ b/Lib/test/pickletester.py
@@ -3244,6 +3244,7 @@ def test_builtin_types(self):
             'BuiltinImporter': (3, 3),
             'str': (3, 4),  # not interoperable with Python < 3.4
             'frozendict': (3, 15),
+            'sentinel': (3, 15),
         }
         for t in builtins.__dict__.values():
             if isinstance(t, type) and not issubclass(t, BaseException):

sunmy2019 · 2026-04-24T17:14:44Z

Buildbot run: A few failures look unrelated

I opened #148967 to track it.

JelleZijlstra and others added 11 commits April 16, 2026 20:45

Initial implementation of PEP 661 v2 (sentinels)

559e527

Update Doc/library/functions.rst

ededfb7

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Update Doc/library/functions.rst

39f364c

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

gc, name

0adf314

C API

e4a106a

not needed

e5b8789

use it for NoExtraItems

bdcb400

tweaks

cc4545c

fix warning?

be58215

blurb

91de05b

attribute

4a970a6

JelleZijlstra requested review from a team, AA-Turner, AlexWaygood, ZeroIntensity, emmatyping, ericsnowcurrently and erlend-aasland as code owners April 21, 2026 13:59

bedevere-app Bot added the awaiting core review label Apr 21, 2026

bedevere-app Bot mentioned this pull request Apr 21, 2026

Implement PEP 661 Sentinel Values #148829

Open

JelleZijlstra added the DO-NOT-MERGE label Apr 21, 2026

JelleZijlstra mentioned this pull request Apr 21, 2026

PEP 661 -- Sentinel Values python/steering-council#258

Closed

5 tasks

johnslavik self-requested a review April 22, 2026 09:44

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

Comment thread Lib/typing.py

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

ZeroIntensity reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

Comment thread Objects/sentinelobject.c Outdated

Comment thread Objects/sentinelobject.c

Comment thread Objects/sentinelobject.c

refactors

9cfd101

eendebakpt reviewed Apr 22, 2026

View reviewed changes

Comment thread Objects/sentinelobject.c Outdated

Update Objects/sentinelobject.c

a851235

Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>

fix

2beb1c2

sunmy2019 self-requested a review April 23, 2026 19:42

JelleZijlstra removed the DO-NOT-MERGE label Apr 24, 2026

Merge branch 'main' into pep661

e2d92a1

hugovk reviewed Apr 24, 2026

View reviewed changes

Comment thread Doc/c-api/sentinel.rst Outdated

Update Doc/c-api/sentinel.rst

53a84b6

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

JelleZijlstra added the 🔨 test-with-buildbots Test PR w/ buildbots; report in status section label Apr 24, 2026

bedevere-bot removed the 🔨 test-with-buildbots Test PR w/ buildbots; report in status section label Apr 24, 2026

ZeroIntensity approved these changes Apr 24, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Apr 24, 2026

sunmy2019 reviewed Apr 24, 2026

View reviewed changes

sunmy2019 approved these changes Apr 24, 2026

View reviewed changes

sunmy2019 reviewed Apr 24, 2026

View reviewed changes

		module_name should be the name of an importable module if the sentinel
		should support pickling.

-   *module_name* should be the name of an importable module if the sentinel
-   should support pickling.
+   For pickling to work, *module_name* must be the name of an importable
+   module, and the sentinel must be accessible from that module under a
+   path matching *name*.  Pickle treats *name* as a global variable name
+   in *module_name* (see :meth:`object.__reduce__`).

-   Sentinels importable from their defining module by name preserve their
-   identity when pickled and unpickled.  Sentinels that are not importable by
-   module and name are not picklable.
+   Sentinels are pickled using the standard mechanism for named global
+   objects. :meth:`sentinel.__reduce__` returns :attr:`~sentinel.__name__`,
+   which pickle interprets as the name of a global variable in
+   :attr:`~sentinel.__module__`. Sentinels that are not accessible from their
+   module under that name are not picklable.

Uh oh!

Conversation

JelleZijlstra commented Apr 21, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-bot commented Apr 24, 2026

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

sunmy2019 Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

sunmy2019 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

sunmy2019 left a comment

Choose a reason for hiding this comment

Uh oh!

sunmy2019 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sunmy2019 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

sunmy2019 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

sunmy2019 Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sunmy2019 commented Apr 24, 2026

Uh oh!

sunmy2019 commented Apr 24, 2026

Uh oh!

sunmy2019 commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

JelleZijlstra commented Apr 21, 2026 •

edited by github-actions Bot

Loading

sunmy2019 Apr 24, 2026 •

edited

Loading

sunmy2019 left a comment •

edited

Loading

sunmy2019 Apr 24, 2026 •

edited

Loading

JelleZijlstra commented Apr 24, 2026 •

edited

Loading